Bookmarks, scenes and tours

Bookmarks are views the author saved; scenes are views you capture - the camera, what is shown, slicers, selection and basemap in one plain object you can store anywhere. The same scene becomes a link that opens the map exactly there, and a tour plays a sequence of views the author recorded.

Open this example on its own

What to notice

  • getBookmarks() is empty unless the author ticked Show a bookmarks control when publishing - the author decides whether bookmarks are offered.
  • A scene survives a re-publish: parts that no longer exist are skipped and reported, the rest applies.
  • sceneToUrl puts the scene in the URL fragment, which browsers never send to a server.
  • While a tour plays, viewChanged carries reason: "tour".

The code

The complete page. Swap in your own publish id, and ask the map's author to add your site to its allowed origins.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Bookmarks, scenes and tours - Icon Map Embed API</title>
  <link rel="stylesheet" href="https://www.icon-map.com/embed-examples/examples.css"> <!-- demo styling only -->
</head>
<body>
  <div class="ex-bar">
    <span class="ex-label">Bookmarks</span>
    <span id="bookmarks" class="ex-chips"></span>
    <span class="ex-spacer"></span>
    <button id="tour">Play the tour</button>
  </div>
  <div class="ex-bar">
    <span class="ex-label">Your own views</span>
    <button id="save">Save this view</button>
    <span id="saved" class="ex-chips"></span>
    <span class="ex-spacer"></span>
    <button id="link">Copy a link to this view</button>
    <button id="reset">Reset</button>
  </div>
  <div class="ex-main"><div id="map"></div></div>

  <script src="https://www.icon-map.com/js/iconmap-embed/2/iconmap-embed.umd.min.js"></script>
  <script>
    const el = document.getElementById("map");
    const map = IconMapEmbed.embed(el, {
      publishId: "pub_...",
      // The map is a globe: let this page's own background show in the space around it.
      background: "transparent",
      // This page draws its own bookmark bar, so hide the map's.
      chrome: { bookmarksBar: false, layerControl: false },
      visibility: { visuals: { "chart-continent": false, "slicer-continent": false, "slicer-size": false, "slicer-capital": false } },
      events: ["bookmarkApplied", "tourStateChanged"],
    });
    map.ready.catch((error) => console.error(error.code, error.message));

    // --- bookmarks: views the map's author saved ---------------------------------
    map.getBookmarks().then((bookmarks) => {
      for (const bookmark of bookmarks) {
        const button = Object.assign(document.createElement("button"), { textContent: bookmark.name, title: bookmark.description ?? "" });
        button.dataset.bookmark = bookmark.id;
        button.onclick = () => map.applyBookmark({ bookmarkId: bookmark.id, animate: true });
        document.getElementById("bookmarks").append(button);
      }
    });
    map.on("bookmarkApplied", ({ bookmarkId }) => {
      for (const b of document.querySelectorAll("[data-bookmark]")) b.classList.toggle("on", b.dataset.bookmark === bookmarkId);
    });

    // --- scenes: views YOU capture - camera, layers, slicers, selection, basemap --------
    // A scene is a plain object: keep it in localStorage, your database, a URL.
    const scenes = [];
    document.getElementById("save").onclick = async () => {
      const scene = await map.captureScene();
      const index = scenes.push(scene);
      const button = Object.assign(document.createElement("button"), { textContent: `View ${index}` });
      button.onclick = () => map.applyScene({ scene, animate: true });
      document.getElementById("saved").append(button);
    };

    // The same scene as a link that opens the map exactly here - no code on the page that opens it.
    document.getElementById("link").onclick = async () => {
      const scene = await map.captureScene({ include: ["camera", "visibility", "slicers"] });
      const link = IconMapEmbed.sceneToUrl(map.iframe.src.split("#")[0], { scene });
      await navigator.clipboard.writeText(link);
      document.getElementById("link").textContent = "Copied";
      setTimeout(() => (document.getElementById("link").textContent = "Copy a link to this view"), 1500);
    };

    document.getElementById("reset").onclick = () => map.resetScene();

    // --- tours: a sequence of views the author recorded -------------------------------
    let playing = null;
    document.getElementById("tour").onclick = async () => {
      if (playing) return map.stopTour();
      const [tour] = await map.getTours();
      if (tour) map.playTour({ tourId: tour.id });
    };
    map.on("tourStateChanged", ({ tourId, state }) => {
      playing = state === "ended" ? null : tourId;
      document.getElementById("tour").textContent = playing ? "Stop the tour" : "Play the tour";
      document.getElementById("tour").classList.toggle("on", !!playing);
    });
  </script>
</body>
</html>

Read more